package com.g0dkar.leet.util.ognl.typeConversion;

import com.g0dkar.leet.util.ognl.LeetOGNLNullHandler;

/**
 * Interface for {@link LeetOGNLTypeConverter JHeat Type Converters}. These classes will be triggered by the OGNL when
 * needed. They must provide conversions to and from {@link String} to {@link Object} and vice-versa.
 * 
 * @author Rafael g0dkar Lins
 * 
 */
public interface TypeConverter {
	/**
	 * Converts a {@link Object} into it's {@link String} representation.
	 * 
	 * @param value
	 *            The Object
	 * @param genericTypes
	 *            A {@link Class} for the generic type of the Object (e.g. if it's a <code>List&lt;String&gt;</code> then
	 *            this parameter should be <code>String.class</code>). This information is not always available.
	 * @return The String representation of the Object
	 * @throws Exception
	 *             Something went wrong...
	 */
	public String toString(Object value, Class<?>... genericTypes) throws Exception;
	
	/**
	 * Converts a {@link Object} into it's <strong>Human-Readable</strong> {@link String} representation.
	 * 
	 * @param value
	 *            The Object
	 * @param genericTypes
	 *            A {@link Class} for the generic type of the Object (e.g. if it's a <code>List&lt;String&gt;</code> then
	 *            this parameter should be <code>String.class</code>). This information is not always available.
	 * @return The Human-Readable String representation of the Object
	 * @throws Exception
	 *             Something went wrong...
	 */
	public String toDisplayableString(Object value, Class<?>... genericTypes) throws Exception;
	
	/**
	 * Converts a {@link String} representation of a {@link Object} into said Object.
	 * 
	 * @param value
	 *            The String representation of the Object
	 * @param toType
	 *            The Object's {@link Class} (type)
	 * @param genericTypes TODO
	 * @return The converted Object
	 * @throws Exception
	 *             Something went wrong...
	 */
	public Object fromString(String value, Class<?> toType, Class<?>... genericTypes) throws Exception;
	
	/**
	 * Creates a new instance of a {@link Class type} this converter can handle. It should do the same as
	 * <code>fromString("<em>default value for the given type</em>", toType)</code>. This method is used mainly by the
	 * {@link LeetOGNLNullHandler} for creating new instances for <code>null</code> values for the OGNL Engine.
	 * 
	 * @param toType
	 *            The Object's {@link Class} (type)
	 * @return The converted Object
	 * @throws Exception
	 *             Something went wrong...
	 */
	public Object newInstance(Class<?> toType) throws Exception;
	
	/**
	 * Used by the {@link TypeConverterManager} to check wether this converter can or cannot convert a given
	 * {@link Class type}.
	 * 
	 * @param toType
	 *            The {@link Class type}
	 * 
	 * @return <code>true</code> if this TypeConverter can handle conversions of this {@link Class type}.
	 */
	public boolean canConvert(Class<?> toType);
}
